Next.js Route Handlerit: Kattava opas API-päätepisteiden luomiseen

Next.js on mullistanut tavan, jolla rakennamme verkkosovelluksia tehokkailla ominaisuuksillaan, kuten palvelinpuolen renderöinnillä, staattisten sivustojen generoinnilla ja nyt, Route Handlereilla. Route Handlerit tarjoavat joustavan ja tehokkaan tavan luoda API-päätepisteitä suoraan Next.js-sovelluksesi sisällä. Tämä opas tutkii Route Handlereiden konseptia, niiden etuja ja kuinka niitä käytetään tehokkaasti vankkojen API-rajapintojen rakentamiseen.

Mitä ovat Next.js Route Handlerit?

Route Handlerit ovat Next.js-projektin app-hakemistossa määriteltyjä funktioita, jotka käsittelevät saapuvia HTTP-pyyntöjä. Toisin kuin vanhempi pages/api-lähestymistapa (joka käyttää API-reittejä), Route Handlerit tarjoavat virtaviivaisemman ja joustavamman tavan määrittää API-päätepisteitä React-komponenttiesi rinnalla. Ne ovat olennaisesti serverless-funktioita, jotka suoritetaan reunalla (edge) tai valitsemassasi palvelinympäristössä.

Ajattele Route Handlereita Next.js-sovelluksesi backend-logiikkana, joka vastaa pyyntöjen käsittelystä, tietokantojen kanssa toimimisesta ja vastausten palauttamisesta.

Route Handlereiden käytön edut

• Yhteissijoittelu: Route Handlerit sijaitsevat suoraan React-komponenttiesi rinnalla app-hakemistossa, mikä edistää parempaa organisointia ja koodin ylläpidettävyyttä.
• TypeScript-tuki: Sisäänrakennettu TypeScript-tuki takaa tyyppiturvallisuuden ja parantaa kehittäjäkokemusta.
• Middleware-integraatio: Integroi helposti middleware-ohjelmistoja tehtäviin, kuten autentikointiin, auktorisointiin ja pyyntöjen validointiin.
• Striimaustuki: Route Handlerit voivat striimata dataa, mikä mahdollistaa vastausten lähettämisen inkrementaalisesti, mikä on hyödyllistä suurille datajoukoille tai pitkäkestoisille prosesseille.
• Edge-funktiot: Ota Route Handlerit käyttöön Edge-funktioina matalan viiveen vastauksille lähempänä käyttäjiäsi, hyödyntäen globaaleja CDN-verkkoja.
• Yksinkertaistettu API-suunnittelu: Route Handlerit tarjoavat selkeän ja intuitiivisen API:n pyyntöjen ja vastausten käsittelyyn.
• Server Actions -integraatio: Tiivis integraatio Server Actions -toimintojen kanssa mahdollistaa saumattoman kommunikaation asiakaspuolen komponenttien ja palvelinpuolen logiikan välillä.

Next.js-projektin pystyttäminen

Ennen kuin sukellat Route Handlereihin, varmista, että sinulla on Next.js-projekti pystytettynä app-hakemiston kanssa. Jos aloitat uuden projektin, käytä seuraavaa komentoa:

            npx create-next-app@latest my-nextjs-app
            

              
                Copy
              
            
          

Valitse asennusprosessin aikana app-hakemisto ottaaksesi uuden reititysjärjestelmän käyttöön.

Ensimmäisen Route Handlerin luominen

Luodaan yksinkertainen API-päätepiste, joka palauttaa JSON-vastauksen. Luo uusi hakemisto app-hakemiston sisään, esimerkiksi /app/api/hello. Luo tämän hakemiston sisään tiedosto nimeltä route.ts (tai route.js, jos et käytä TypeScriptiä).

Tässä on koodi ensimmäiselle Route Handlerillesi:

            // app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });
}

            

              
                Copy
              
            
          

Selitys:

• import { NextResponse } from 'next/server';: Tuo NextResponse-olion, jota käytetään API-vastausten rakentamiseen.
• export async function GET(request: Request) { ... }: Määrittelee asynkronisen funktion, joka käsittelee GET-pyyntöjä /api/hello-päätepisteeseen. request-parametri antaa pääsyn saapuvaan pyyntö-olioon.
• return NextResponse.json({ message: 'Hello from Next.js Route Handlers!' });: Luo JSON-vastauksen viestillä ja palauttaa sen käyttämällä NextResponse.json()-metodia.

Nyt voit käyttää tätä päätepistettä siirtymällä osoitteeseen /api/hello selaimessasi tai käyttämällä työkalua kuten curl tai Postman.

Eri HTTP-metodien käsittely

Route Handlerit tukevat useita HTTP-metodeja, kuten GET, POST, PUT, DELETE, PATCH ja OPTIONS. Voit määrittää erilliset funktiot kullekin metodille samassa route.ts-tiedostossa.

            // app/api/users/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 // Logiikka kaikkien käyttäjien hakemiseksi tietokannasta
 const users = [{ id: 1, name: 'John Doe' }, { id: 2, name: 'Jane Smith' }]; // Esimerkkidata
 return NextResponse.json(users);
}

export async function POST(request: Request) {
 const data = await request.json(); // Jäsennä pyynnön runko JSON-muodossa
 // Logiikka uuden käyttäjän luomiseksi tietokantaan 'data'-tietojen avulla
 const newUser = { id: 3, name: data.name, email: data.email }; // Esimerkki
 return NextResponse.json(newUser, { status: 201 }); // Palauta uusi käyttäjä 201 Created -statuskoodilla
}

            

              
                Copy
              
            
          

Selitys:

• GET-funktio hakee listan käyttäjistä (simuloitu tässä) ja palauttaa heidät JSON-vastauksena.
• POST-funktio jäsentää pyynnön rungon JSON-muodossa, luo uuden käyttäjän (simuloitu) ja palauttaa uuden käyttäjän 201 Created -statuskoodilla.

Pyyntödatan käsittely

request-olio tarjoaa pääsyn erilaisiin tietoihin saapuvasta pyynnöstä, mukaan lukien otsakkeet, kyselyparametrit ja pyynnön runko.

Otsakkeet

Voit käyttää pyynnön otsakkeita request.headers-ominaisuuden avulla:

            export async function GET(request: Request) {
 const userAgent = request.headers.get('user-agent');
 console.log('User Agent:', userAgent);
 return NextResponse.json({ userAgent });
}

            

              
                Copy
              
            
          

Kyselyparametrit

Päästäksesi käsiksi kyselyparametreihin voit käyttää URL-konstruktoria:

            export async function GET(request: Request) {
 const url = new URL(request.url);
 const searchParams = new URLSearchParams(url.search);
 const id = searchParams.get('id');
 console.log('ID:', id);
 return NextResponse.json({ id });
}

            

              
                Copy
              
            
          

Pyynnön runko

POST-, PUT- ja PATCH-pyynnöissä voit käyttää pyynnön runkoa request.json()- tai request.text()-metodeilla, riippuen sisällön tyypistä.

            export async function POST(request: Request) {
 const data = await request.json();
 console.log('Data:', data);
 return NextResponse.json({ receivedData: data });
}

            

              
                Copy
              
            
          

Vastausten palauttaminen

NextResponse-oliota käytetään API-vastausten rakentamiseen. Se tarjoaa useita metodeja otsakkeiden, statuskoodien ja vastausrungon asettamiseen.

JSON-vastaukset

Käytä NextResponse.json()-metodia palauttaaksesi JSON-vastauksia:

            return NextResponse.json({ message: 'Success!', data: { name: 'John Doe' } }, { status: 200 });

            

              
                Copy
              
            
          

Tekstivastaukset

Käytä new Response()-konstruktoria palauttaaksesi pelkkää tekstiä sisältäviä vastauksia:

            return new Response('Hello, world!', { status: 200, headers: { 'Content-Type': 'text/plain' } });

            

              
                Copy
              
            
          

Uudelleenohjaukset

Käytä NextResponse.redirect()-metodia ohjataksesi käyttäjät toiseen URL-osoitteeseen:

            import { redirect } from 'next/navigation';
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.redirect(new URL('/new-location', request.url));
}

            

              
                Copy
              
            
          

Otsakkeiden asettaminen

Voit asettaa mukautettuja otsakkeita käyttämällä headers-optiota NextResponse.json()- tai new Response()-metodeissa:

            return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'no-cache' } });

            

              
                Copy
              
            
          

Middleware-integraatio

Middleware mahdollistaa koodin suorittamisen ennen kuin pyyntöä käsitellään Route Handlerissasi. Tämä on hyödyllistä autentikointiin, auktorisointiin, lokitukseen ja muihin läpileikkaaviin toimintoihin.

Luodaksesi middlewarin, luo tiedosto nimeltä middleware.ts (tai middleware.js) app-hakemistoon tai mihin tahansa alihakemistoon. Middleware soveltuu kaikkiin reitteihin kyseisessä hakemistossa ja sen alihakemistoissa.

            // app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
 const token = request.cookies.get('auth-token');

 if (!token) {
 return NextResponse.redirect(new URL('/login', request.url));
 }

 return NextResponse.next();
}

export const config = {
 matcher: ['/protected/:path*'], // Sovella tätä middlewarea polkuihin, jotka alkavat /protected/
};

            

              
                Copy
              
            
          

Selitys:

• middleware-funktio tarkistaa autentikointitokenin pyynnön evästeistä.
• Jos token puuttuu, se ohjaa käyttäjän kirjautumissivulle.
• Muussa tapauksessa se antaa pyynnön edetä Route Handlerille.
• config-olio määrittää, että tätä middlewarea tulisi soveltaa vain reitteihin, jotka alkavat /protected/.

Virheidenkäsittely

Oikeaoppinen virheidenkäsittely on ratkaisevan tärkeää vankkojen API-rajapintojen rakentamisessa. Voit käyttää try...catch-lohkoja poikkeusten käsittelyyn ja asianmukaisten virhevastausten palauttamiseen.

            export async function GET(request: Request) {
 try {
 // Simuloi virhettä
 throw new Error('Something went wrong!');
 } catch (error: any) {
 console.error('Error:', error);
 return NextResponse.json({ error: error.message }, { status: 500 });
 }
}

            

              
                Copy
              
            
          

Selitys:

• try...catch-lohko nappaa kaikki poikkeukset, jotka tapahtuvat Route Handlerin sisällä.
• catch-lohkossa virhe kirjataan lokiin, ja palautetaan virhevastaus 500 Internal Server Error -statuskoodilla.

Striimaavat vastaukset

Route Handlerit tukevat striimaavia vastauksia, mikä mahdollistaa datan lähettämisen asiakkaalle inkrementaalisesti. Tämä on erityisen hyödyllistä suurille datajoukoille tai pitkäkestoisille prosesseille.

            import { Readable } from 'stream';
import { NextResponse } from 'next/server';

async function* generateData() {
 for (let i = 0; i < 10; i++) {
 await new Promise(resolve => setTimeout(resolve, 500)); // Simuloi viivettä
 yield `Data chunk ${i}\n`;
 }
}

export async function GET(request: Request) {
 const readableStream = Readable.from(generateData());

 return new Response(readableStream, {
 headers: { 'Content-Type': 'text/plain; charset=utf-8' },
 });
}

            

              
                Copy
              
            
          

Selitys:

• generateData-funktio on asynkroninen generaattori, joka tuottaa datanpaloja viiveellä.
• Readable.from()-metodi luo luettavan striimin generaattorista.
• Response-olio luodaan luettavan striimin kanssa runkona, ja Content-Type-otsakkeeksi asetetaan text/plain.

Autentikointi ja auktorisointi

API-päätepisteiden suojaaminen on ratkaisevan tärkeää. Voit toteuttaa autentikoinnin ja auktorisoinnin käyttämällä middlewarea tai suoraan Route Handlereidesi sisällä.

Autentikointi

Autentikointi vahvistaa pyynnön tehneen käyttäjän henkilöllisyyden. Yleisiä autentikointimenetelmiä ovat:

• JWT (JSON Web Tokens): Luo token onnistuneen kirjautumisen yhteydessä ja vahvista se seuraavissa pyynnöissä.
• Sessiopohjainen autentikointi: Käytä evästeitä sessiotunnisteiden tallentamiseen ja vahvista ne jokaisessa pyynnössä.
• OAuth: Delegoi autentikointi kolmannen osapuolen palveluntarjoajalle, kuten Googlelle tai Facebookille.

Tässä on esimerkki JWT-autentikoinnista middlewarin avulla:

            // app/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import jwt from 'jsonwebtoken';

const secret = process.env.JWT_SECRET || 'your-secret-key'; // Korvaa vahvalla, satunnaisesti generoidulla salasanalla

export function middleware(request: NextRequest) {
 const token = request.cookies.get('auth-token')?.value;

 if (!token) {
 return NextResponse.json({ message: 'Authentication required' }, { status: 401 });
 }

 try {
 jwt.verify(token, secret);
 return NextResponse.next();
 } catch (error) {
 return NextResponse.json({ message: 'Invalid token' }, { status: 401 });
 }
}

export const config = {
 matcher: ['/api/protected/:path*'],
};

            

              
                Copy
              
            
          

Auktorisointi

Auktorisointi määrittää, mihin resursseihin käyttäjällä on pääsy. Tämä perustuu tyypillisesti rooleihin tai oikeuksiin.

Voit toteuttaa auktorisoinnin Route Handlereidesi sisällä tarkistamalla käyttäjän roolit tai oikeudet ja palauttamalla virheen, jos heillä ei ole pääsyä.

            // app/api/admin/route.ts
import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 // Oletetaan, että sinulla on funktio käyttäjän roolin saamiseksi tokenista tai sessiosta
 const userRole = await getUserRole(request);

 if (userRole !== 'admin') {
 return NextResponse.json({ message: 'Unauthorized' }, { status: 403 });
 }

 // Logiikka admin-datan hakemiseksi
 const adminData = { message: 'Admin data' };
 return NextResponse.json(adminData);
}

async function getUserRole(request: Request): Promise {
 // Korvaa tämä todellisella logiikallasi käyttäjän roolin poimimiseksi pyynnöstä
 // Tämä voi sisältää JWT-tokenin tarkistamisen tai session tarkistamisen
 return 'admin'; // Esimerkki: kovakoodattu rooli esittelyä varten
}

            

              
                Copy
              
            
          

Route Handlereiden käyttöönotto

Route Handlerit otetaan käyttöön serverless-funktioina valitsemallasi hosting-alustalla. Next.js tukee useita käyttöönottopalveluita, kuten Vercel, Netlify, AWS ja muita.

Vercelille käyttöönotto on niin yksinkertaista kuin Git-repositorion yhdistäminen Verceliin ja koodin puskeminen. Vercel tunnistaa automaattisesti Next.js-projektisi ja ottaa Route Handlerisi käyttöön serverless-funktioina.

Edistyneet tekniikat

Edge-funktiot

Route Handlerit voidaan ottaa käyttöön Edge-funktioina, jotka suoritetaan CDN-verkon reunalla, lähempänä käyttäjiäsi. Tämä voi merkittävästi vähentää viivettä ja parantaa suorituskykyä.

Ottaaksesi Route Handlerin käyttöön Edge-funktiona, lisää edge-ajonaika route.ts-tiedostoosi:

            export const runtime = 'edge';

import { NextResponse } from 'next/server';

export async function GET(request: Request) {
 return NextResponse.json({ message: 'Hello from the Edge!' });
}

            

              
                Copy
              
            
          

Server Actions

Server Actions -toiminnot mahdollistavat palvelinpuolen koodin suorittamisen suoraan React-komponenteistasi. Route Handlerit ja Server Actions toimivat saumattomasti yhdessä, mahdollistaen monimutkaisten sovellusten rakentamisen helposti.

Tässä on esimerkki Server Actionin käytöstä Route Handlerin kutsumiseen:

            // app/components/MyComponent.tsx
'use client';
import { useState } from 'react';
import { useRouter } from 'next/navigation';

async function handleSubmit(data: FormData) {
 'use server';

 const name = data.get('name');
 const email = data.get('email');

 const response = await fetch('/api/users', {
 method: 'POST',
 body: JSON.stringify({ name, email }),
 });

 if (response.ok) {
 router.refresh(); // Päivitä sivu näyttämään muutokset
 }
}

export default function MyComponent() {
 const router = useRouter();

 return (
 

 Nimi:
 


 Sähköposti:
 


 Luo käyttäjä
 
 );
}

            

              
                Copy
              
            
          

Välimuisti

Välimuistin käyttö voi merkittävästi parantaa API-päätepisteidesi suorituskykyä. Voit käyttää Cache-Control-otsaketta hallitaksesi, miten vastauksiasi tallennetaan selaimiin ja CDN-verkkoihin.

            return NextResponse.json({ message: 'Success!' }, { status: 200, headers: { 'Cache-Control': 'public, max-age=3600' } });

            

              
                Copy
              
            
          

Tämä esimerkki asettaa Cache-Control-otsakkeen arvoon public, max-age=3600, mikä kertoo selaimille ja CDN-verkoille, että vastaus voidaan tallentaa välimuistiin tunniksi.

Parhaat käytännöt

• Käytä TypeScriptiä: Hyödynnä TypeScriptin tyyppiturvallisuutta parantaaksesi koodin laatua ja ehkäistäksesi virheitä.
• Validoi pyynnöt: Validoi saapuvat pyynnöt varmistaaksesi datan eheyden ja estääksesi haitallisen syötteen.
• Käsittele virheet siististi: Toteuta asianmukainen virheidenkäsittely tarjotaksesi informatiivisia virheilmoituksia asiakkaille.
• Suojaa päätepisteesi: Toteuta autentikointi ja auktorisointi suojataksesi API-päätepisteesi.
• Käytä middlewarea: Käytä middlewarea läpileikkaaviin toimintoihin, kuten autentikointiin, lokitukseen ja pyyntöjen validointiin.
• Tallenna vastaukset välimuistiin: Käytä välimuistia parantaaksesi API-päätepisteidesi suorituskykyä.
• Valvo API-rajapintojasi: Valvo API-rajapintojasi tunnistaaksesi ja ratkaistaksesi ongelmat nopeasti.
• Dokumentoi API-rajapintasi: Dokumentoi API-rajapintasi, jotta muiden kehittäjien on helppo käyttää niitä. Harkitse työkalujen, kuten Swagger/OpenAPI, käyttöä API-dokumentaatioon.

Esimerkkejä todellisesta maailmasta

Tässä on muutamia esimerkkejä todellisesta maailmasta, kuinka Route Handlereita voidaan käyttää:

• Verkkokaupan API: Luo API-päätepisteitä tuotteiden, tilausten ja käyttäjien hallintaan.
• Sosiaalisen median API: Luo API-päätepisteitä twiittien julkaisemiseen, käyttäjien seuraamiseen ja aikajanojen hakemiseen.
• Sisällönhallintajärjestelmän (CMS) API: Luo API-päätepisteitä sisällön, käyttäjien ja asetusten hallintaan.
• Data-analytiikan API: Luo API-päätepisteitä datan keräämiseen ja analysointiin. Esimerkiksi Route Handler voisi vastaanottaa dataa seurantapikseleistä eri verkkosivustoilta ja yhdistää tiedot raportointia varten.

Kansainvälisen verkkokaupan esimerkki: Route Handler, jota käytetään tuotteiden hintojen hakemiseen käyttäjän maan perusteella. Päätepiste voisi käyttää pyynnön maantieteellistä sijaintia (johdettu IP-osoitteesta) määrittääkseen käyttäjän sijainnin ja palauttaakseen hinnat oikeassa valuutassa. Tämä edistää lokalisoitua ostokokemusta.

Globaalin autentikoinnin esimerkki: Route Handler, joka toteuttaa monivaiheisen tunnistautumisen (MFA) käyttäjille maailmanlaajuisesti. Tämä voisi sisältää tekstiviestikoodien lähettämisen tai autentikointisovellusten käytön, kunnioittaen samalla eri alueiden tietosuojamääräyksiä ja tietoliikenneinfrastruktuureja.

Monikielisen sisällön toimitus: Route Handler, joka toimittaa sisältöä käyttäjän ensisijaisella kielellä. Tämä voidaan määrittää pyynnön `Accept-Language`-otsakkeesta. Tämä esimerkki korostaa asianmukaisen UTF-8-koodauksen ja oikealta vasemmalle -kielituen tarvetta tarvittaessa.

Yhteenveto

Next.js Route Handlerit tarjoavat tehokkaan ja joustavan tavan luoda API-päätepisteitä suoraan Next.js-sovelluksesi sisällä. Hyödyntämällä Route Handlereita voit rakentaa vankkoja API-rajapintoja helposti, sijoittaa backend-logiikkasi React-komponenttiesi rinnalle ja hyödyntää ominaisuuksia, kuten middlewarea, striimausta ja Edge-funktioita.

Tämä kattava opas on käsitellyt kaiken perusasetuksista edistyneisiin tekniikoihin. Noudattamalla tässä oppaassa esitettyjä parhaita käytäntöjä voit rakentaa laadukkaita API-rajapintoja, jotka ovat turvallisia, suorituskykyisiä ja ylläpidettäviä.